# Wi-Fi/Bluetooth ***Copyright © Quectel Wireless Solutions Co., Ltd. 2026. All rights reserved.*** --- The **Quectel Pi H1 smart single-board computer** supports the QCA1023 SDIO Wi-Fi and HCI UART Bluetooth modules. Wi-Fi can be enabled, scanned, connected and network verified through the nmcli command. Bluetooth can be initiated, peripheral pairing and connection achieved through commands such as hciattach, hciconfig, and bluetoothctl. It can also be configured as a BLE peripheral for broadcasting, meeting various wireless connection requirements. # Wi-Fi usage The **Quectel Pi H1 smart single‑board computer** supports the QCA1023 SDIO Wi‑Fi module. This section introduces how to configure Wi‑Fi connections using the `nmcli` command-line tool. > `nmcli` is a user‑space command-line utility provided by NetworkManager on Linux systems. It is used for managing network connections, especially in environments without a graphical interface or in automation scripts. It supports configuration and management of Ethernet, Wi‑Fi, VLAN, bridge, proxy, VPN, and other types of network connections. ## Enable Wi-Fi Use the following command to turn on Wi‑Fi functionality. It is equivalent to enabling the Wi‑Fi switch in a desktop environment: ```shell nmcli radio wifi on ``` ## View available Wi-Fi networks Execute the following command to scan and list all Wi‑Fi networks detected by the wireless interface. The command displays nearby Wi‑Fi networks and information such as SSID, signal strength, channel, and security type: ```shell nmcli dev wifi list ifname wlan0 ``` > This command instructs interface `wlan0` to perform the scan. You may modify the interface name based on the actual hardware. Key parameter description: | **Parameters** | **description** | | --- | --- | | IN-USE | | | BSSID | MAC address of the access point | | SSID | Wi‑Fi network name | | MODE | Operation mode, Infra indicates infrastructure mode (common) | | CHAN | Channel number | | RATE | Maximum data rate | | SIGNAL | Signal strength | | BARS | Bar graphical signal indicator | | SECURITY | Security protocol (such as WPA2, WPA3, and 802.1X) | Example output: ```shell root@QuectelPi:~# nmcli dev wifi list ifname wlan0 IN-USE BSSID SSID MODE CHAN RATE SIGNAL BARS SECURITY 64:09:80:76:42:BE Xiaomi_42BD Infra 11 130 Mbit/s 100 ▂▄▆█ WPA1 WPA2 * F8:5E:3C:01:F8:18 xiupax Infra 11 130 Mbit/s 100 ▂▄▆█ -- 9C:9D:7E:F7:30:5E tdz Infra 2 130 Mbit/s 97 ▂▄▆█ WPA1 WPA2 E2:F1:E1:57:D5:C6 gms-wifi Infra 1 0 Mbit/s 95 ▂▄▆█ WPA1 WPA2 E2:F1:E1:57:D5:C8 cit-test-5g Infra 1 0 Mbit/s 94 ▂▄▆█ WPA2 48:5F:08:BB:BA:41 TP-LINK_BA41 Infra 11 270 Mbit/s 87 ▂▄▆█ -- 64:09:80:76:42:BF Xiaomi_42BD_5G Infra 157 270 Mbit/s 82 ▂▄▆█ WPA1 WPA2 B4:2F:03:DA:23:B5 5G_RRO_A23B5 Infra 157 135 Mbit/s 79 ▂▄▆_ WPA1 WPA2 A2:A7:90:A7:5B:A0 LSMate30 Infra 149 270 Mbit/s 77 ▂▄▆_ WPA2 A4:00:E2:EF:F7:83 Quectel-HF Infra 1 260 Mbit/s 74 ▂▄▆_ WPA1 WPA2 802.1X F0:2F:74:2A:41:78 odmtest Infra 1 260 Mbit/s 74 ▂▄▆_ WPA3 2C:CF:67:6B:4A:86 HW-676B4A85 Infra 36 117 Mbit/s 74 ▂▄▆_ WPA1 A4:00:E2:EF:F7:82 Quectel-HF-2.4G Infra 1 260 Mbit/s 72 ▂▄▆_ WPA1 WPA2 802.1X A4:00:E2:EF:F7:80 Quectel-Customer-2.4G Infra 1 260 Mbit/s 72 ▂▄▆_ WPA1 WPA2 66:D6:9A:C6:6D:21 PAXWIFIAP_2.4G Infra 1 130 Mbit/s 72 ▂▄▆_ WPA2 A4:00:E2:EF:F7:90 Quectel-Customer Infra 44 540 Mbit/s 72 ▂▄▆_ WPA1 WPA2 A4:00:E2:EF:F7:92 Quectel-HF Infra 44 540 Mbit/s 72 ▂▄▆_ WPA1 WPA2 802.1X 9C:9D:7E:F7:30:5F tdz Infra 149 270 Mbit/s 70 ▂▄▆_ WPA1 WPA2 34:CE:00:09:E5:A8 SW_test Infra 6 130 Mbit/s 69 ▂▄▆_ WPA1 WPA2 E2:F1:E1:57:D5:CA gms-wifi_5G Infra 149 270 Mbit/s 69 ▂▄▆_ WPA1 WPA2 E2:F1:E1:57:D5:CE cit-test-5g Infra 149 270 Mbit/s 69 ▂▄▆_ WPA2 F0:2F:74:2A:41:7C odmtest-5G Infra 161 540 Mbit/s 65 ▂▄▆_ WPA2 A4:00:E2:EF:F8:52 Quectel-HF Infra 36 540 Mbit/s 57 ▂▄▆_ WPA1 WPA2 802.1X A4:00:E2:EF:F8:50 Quectel-Customer Infra 36 540 Mbit/s 57 ▂▄▆_ WPA1 WPA2 3C:7C:3F:0B:94:FC HWTEST Infra 161 540 Mbit/s 52 ▂▄__ WPA2 A4:00:E2:EF:F4:50 Quectel-Customer Infra 149 540 Mbit/s 49 ▂▄__ WPA1 WPA2 A4:00:E2:EF:F4:52 Quectel-HF Infra 149 540 Mbit/s 47 ▂▄__ WPA1 WPA2 802.1X ``` ## Connect to a Wi-Fi network Select the Wi-Fi network you want to connect to and execute the command `nmcli dev wifi connect "Wi-Fi name" password "Wi-Fi password"` to connect to it. Example: ```shell $ nmcli dev wifi connect "SSID" password "12345678" ifname wlan0 Device 'wlan0' successfully activated with 'd0ef4183-ac40-41d5-8822-2cc174107c77'. ``` If you are connecting to an open network (no password required), the parameter "Wi-Fi password" is not needed. Example: ```shell root@QuectelPi:~# nmcli dev wifi connect "SSID" ifname wlan0 Device 'wlan0' successfully activated with 'd0ef4183-ac40-41d5-8822-2cc174107c77'. ``` ## Verify network status Use `ifconfig` command to view the network interface address. Example: ```shell root@QuectelPi:~# ifconfig eth0 Link encap:Ethernet HWaddr 32:C0:A2:09:FE:40 UP BROADCAST MULTICAST MTU:1500 Metric:1 RX packets:0 errors:0 dropped:0 overruns:0 frame:0 TX packets:0 errors:0 dropped:0 overruns:0 carrier:0 collisions:0 txqueuelen:1000 RX bytes:0 (0.0 B) TX bytes:0 (0.0 B) Interrupt:167 Base address:0x1000 lo Link encap:Local Loopback inet addr:127.0.0.1 Mask:255.0.0.0 inet6 addr: ::1/128 Scope:Host UP LOOPBACK RUNNING MTU:65536 Metric:1 RX packets:75 errors:0 dropped:0 overruns:0 frame:0 TX packets:75 errors:0 dropped:0 overruns:0 carrier:0 collisions:0 txqueuelen:1000 RX bytes:6301 (6.1 KiB) TX bytes:6301 (6.1 KiB) p2p0 Link encap:Ethernet HWaddr 02:03:7F:D6:00:01 UP BROADCAST MULTICAST MTU:1500 Metric:1 RX packets:0 errors:0 dropped:0 overruns:0 frame:0 TX packets:0 errors:0 dropped:0 overruns:0 carrier:0 collisions:0 txqueuelen:3000 RX bytes:0 (0.0 B) TX bytes:0 (0.0 B) wlan0 Link encap:Ethernet HWaddr 00:03:7F:50:00:01 inet addr:192.168.253.211 Bcast:192.168.253.255 Mask:255.255.255.0 UP BROADCAST RUNNING MULTICAST MTU:1500 Metric:1 RX packets:3421 errors:0 dropped:0 overruns:0 frame:0 TX packets:61 errors:0 dropped:0 overruns:0 carrier:0 collisions:0 txqueuelen:3000 RX bytes:151273 (147.7 KiB) TX bytes:7300 (7.1 KiB) ``` From the output, you can see that the wlan0 interface has successfully obtained an IP address. ## Test network Execute the `ping` command to test network connection (replace the IP with your actual gateway IP): - `ping 192.168.1.1` → Tests LAN gateway connection. - `ping 114.114.114.114` → Tests external network connection. - `ping baidu.com` → Tests external connectivity and DNS resolution. # Bluetooth usage The **Quectel Pi H1 smart single-board computer** supports the QCA1023 HCI UART Bluetooth module for Bluetooth peripheral connections. This section introduces how to connect Bluetooth devices such as keyboards and mice. ## Start the Bluetooth module The Bluetooth module connects to the host controller via HCI UART using the HCI H4 protocol. Power on the Bluetooth peripheral via the device node with the following command. (echo 0 powers it off). ```shell echo 1 > /sys/devices/platform/rfkill/bt_en ``` Initialize the Bluetooth module via UART with the `hciattach` command. ```shell hciattach /dev/ttyHS1 qca 3000000 flow ``` Query and enable the HCI Bluetooth device with the `hciconfig` command: ```shell hciconfig hci0 up ``` Query HCI device status with `hciconfig`. If the device shows *UP RUNNING*, Bluetooth has been successfully enabled: ```shell root@QuectelPi:~# hciconfig hci0: Type: Primary Bus: UART BD Address: 00:00:00:00:5A:AD ACL MTU: 1024:7 SCO MTU: 60:8 UP RUNNING RX bytes:783665 acl:1106 sco:0 events:18678 errors:0 TX bytes:4072 acl:57 sco:0 commands:305 errors:0 ``` ## Connect Bluetooth peripherals Execute `bluetoothctl` to enter the Bluetooth configuration tool. When the command prompt changes to `[bluetooth]#`, the device enters Bluetooth control mode. ```shell root@QuectelPi:~# bluetoothctl [bluetooth]# ``` Execute `scan on` to start device discovery, which will display nearby Bluetooth devices. Please enable pairing mode on the target device. ```shell [bluetooth]# scan on ``` After scanning for a while, execute `scan off` to stop scanning. ```shell [bluetooth]# scan off ``` Execute `devices` to list discovered devices and find your Bluetooth device. Here is an example of a Bluetooth mouse. ```shell [bluetooth]# devices Device C3:3E:68:5E:E7:1F MX Master 2S ``` Execute `pair` to pair the device with your peripheral's address. ```shell [bluetooth]# pair C3:3E:68:5E:E7:1F ``` A pairing code prompt may appear during the pairing. Confirm it by clicking "Pair" in the UI or typing `yes` in the terminal so the connection can proceed. If pairing succeeds, CHG logs will appear and the device will be registered to the input device. For example, *input5* below (refer to actual registered addresses). ```shell [CHG] Device C3:3E:68:5E:E7:1F Modalias: usb:v046DpB019d0006 [MX Master 2S]# [ 1157.381232][ T1737] input: MX Master 2S Keyboard as /devices/virtual/misc/uhid/0005:046D:B019.0001/input/input4[ 1157.392409][ T1737] input: MX Master 2S Mouse as /devices/virtual/misc/uhid/0005:046D:B019.0001/input/input5 ``` Mark the device as trusted and connect (skip if your device supports autoconnection): ```shell [MX Master 2S]# trust C3:3E:68:5E:E7:1F Changing C3:3E:68:5E:E7:1F trust succeeded [MX Master 2S]# connect C3:3E:68:5E:E7:1F Attempting to connect to C3:3E:68:5E:E7:1F Connection successful ``` ## Verify peripheral After connection, use the evtest tool to verify the peripheral functionality. Enter `evtest` to view the list of available event devices. Then, select the number corresponding to your device (e.g., event 5 for your mouse). ```shell root@QuectelPi:~# evtest No device specified, scanning all /dev/input/event* Available devices: /dev/input/event0: pm8xxx_vib_ffmemless /dev/input/event1: gpio-keys /dev/input/event2: pmic_pwrkey /dev/input/event3: pmic_resin /dev/input/event4: MX Master 2S Keyboard /dev/input/event5: MX Master 2S Mouse Select the device event number [0-5]: ``` When the following output information appears, the connection is completed. You can test whether events are reported by moving the mouse or pressing its buttons. ```shell Input driver version is 1.0.1 Input device ID: bus 0x5 vendor 0x46d product 0xb019 version 0x6 Input device name: "MX Master 2S Mouse" Supported events: Event type 0 (EV_SYN) Event type 1 (EV_KEY) Event code 272 (BTN_LEFT) Event code 273 (BTN_RIGHT) Event code 274 (BTN_MIDDLE) Event code 275 (BTN_SIDE) Event code 276 (BTN_EXTRA) Event code 277 (BTN_FORWARD) Event code 278 (BTN_BACK) Event code 279 (BTN_TASK) Event code 280 (?) Event code 281 (?) Event code 282 (?) Event code 283 (?) Event code 284 (?) Event code 285 (?) Event code 286 (?) Event code 287 (?) Event type 2 (EV_REL) Event code 0 (REL_X) Event code 1 (REL_Y) Event code 6 (REL_HWHEEL) Event code 8 (REL_WHEEL) Event code 11 (REL_WHEEL_HI_RES) Event code 12 (REL_HWHEEL_HI_RES) Event type 4 (EV_MSC) Event code 4 (MSC_SCAN) Properties: Testing ... (interrupt to exit) Event: time 2618.445029, type 4 (EV_MSC), code 4 (MSC_SCAN), value 90001 Event: time 2618.445029, type 1 (EV_KEY), code 272 (BTN_LEFT), value 1 Event: time 2618.445029, -------------- SYN_REPORT ------------ Event: time 2618.610162, type 4 (EV_MSC), code 4 (MSC_SCAN), value 90001 Event: time 2618.610162, type 1 (EV_KEY), code 272 (BTN_LEFT), value 0 Event: time 2618.610162, -------------- SYN_REPORT ------------ ``` # Configure the Bluetooth device as a BLE peripheral The **Quectel Pi H1** supports configuring the Bluetooth device as a Bluetooth Low Energy (BLE) peripheral for broadcasting, allowing other BLE devices (such as smartphones and tablets) to discover and connect. ## Operation steps 1. **Start Bluetooth advertising** ```shell bluetoothctl> advertise on ``` 1. This command enables the Bluetooth advertising function, creates a Bluetooth advertising instance, and sets the device to be discoverable by nearby Bluetooth devices, preparing for subsequent device pairing and connection. 2. **Configure advertising parameters**, configure via the underlying Bluetooth management protocol: - Set IO capability to `KeyboardDisplay` - Configure extended advertising parameters (connectable mode, broadcast interval 1280ms) - Set advertising data flags (LE General Discoverable Mode, BLE only) - Enable advertising 3. **View device status** ```shell bluetoothctl> show ``` 1. View Bluetooth controller details such as device name, MAC address, supported roles, and GATT services.